Integration Tutorials

These tutorials provide guidance through the necessary steps to use VIDcredentials and VIDconnect. In particular, three different tutorials are presented focusing on different use cases. All use cases together form a user journey that consists of the following steps:

1. A User gets his first credential by going through a process that involves scanning his ID card. This process is explained in detail in VIDwallet create credential description.
2. The user authenticates towards a website, which requests a verifiable ID presentation. The related process is described in section Authenticating Users with OpenID Connect.
3. Once the user is authenticated, he requests a new credential, issued by the government detailed in section Request and Verify credentials.
4. Finally, the user presents this credential to his university in order to get a discount. Section Issue Credentials details this process.

1. OpenID Connect User Authentication Flow

The web application needs to be configured to initiate an OpenID Connect flow towards VIDconnect (Valdiated ID's OpenID Connect Provider), and set up a callback URL to receive the Authorization Code and request the id_token. This process described in detail in the corresponding VIDconnect Integration Guide.

OpenID Discovery URL You can set up your OIDC client by using OIDC Discovery to: https://api.vidchain.net/.well-known/openid-configuration

note

We strongly recommend the use of an OpenID client library like AppAuth-JS or JSO-OAuth2. Alternatively, you can find a comprehensive list of other certified products on the OpenID website: https://openid.net/developers/certified/ or at https://oauth.net/code/.

OpenID Connect SIOP Flow

The steps of the flow are depicted in the figure as well as described below:

1. On a website or webapp, the user selects login using VIDwallet.
2. The OpenID Connect Client initiates an authorization code flow. The user is redirected to https://api.vidchain.net/oauth2/auth?client_id=...&redirect_uri=... where a QR code is shown. It is possible that the relying party request additional identity attributes in this call but in this example a VerifiableIdCredential is requested.
3. The user scans the QR code to authenticate using VIDwallet. The user performs identification and authentication.
4. VIDconnect may call the VIDchain backend for additional information such as for resolving the DID.
5. The user is redirected to the client’s /callback URL along with the authorization code. The web application is using the callback URL to get the id_token from the OIDC provider using the authorization code.
6. The service provider grants access to their services or resources.

note

The id_token includes the DID of the user, which performed the authentication flow.

The Performed Calls in more Detail

Redirect to OIDP

First, the client redirects the requester to VIDconnet's OID provider with an URL in the following format:

https://api.vidchain.net/oauth2/auth?
  response_type=code
  &state=08bd09b6-8544-4f8b-9aef-bdd6f17db6f7
  &redirect_uri=<Your callback URL>
  &client_id=<Your Client ID>
  &scope=openid VerifiableIdCredential
  &nonce=a8d84bc5-1c09-484b-9638-81baf028dfb2

Callback

Once the user is authenticated, the OID provider redirects the user session to the callback URL providing the code:

http(s)://<callback URL>
  ?code=pRt3Lk5I7A....IhUNaPsWPQ
  &scope=openid%20VerifiableIdCredential
  &state=08bd09b6-8544-4f8b-9aef-bdd6f17db6f7

Token endpoint

After receiving the code, your OIDC client needs to call the /token endpoint:

POST to https://api.vidchain.net/oauth2/token

With the following body:

"Content-Type": 'application/x-www-form-urlencoded'
code: code,
redirect_uri: REDIRECT_CALLBACK,
grant_type: "authorization_code",
client_id: CLIENT_ID,
client_secret

An example response is shown below:

{
    "access_token": "7UZT2tlb...UJkdovjfM",
    "expires_in": 3599,
    "id_token": "eyJhbGciOiJSUzI1NiIsImt...qvcFmb8vxqwXjHn9kERSRA",
    "scope": "openid VerifiableIdCredential",
    "token_type": "bearer"
}

2. Verifiable Presentation Flow

In this example, a website requests a presentation of a VerifiableIdCredential using VIDcredentials service.

important

This flow is performed after the user has already performed identification and authentication using the flow described in section OpenID Connect SIOP flow.

The following diagram depicts the whole process flow in detail:

Request a Presentation

A website requests from a user to present a verifiable presentation that is based on a verifiable credential. To do so, a call to the Verifiable Presentation Service of VIDcredentials is performed, detailed in corresponding OpenAPI description Request a Verifiable Presentation.

Following, an example payload that will be sent to the /api/v1/verifiable-presentations-requests endpoint to request a “VerifiableIdCredential”:

{
  "target": "did:vid:0xAf3fAf5F4618a096d242B8f3F8B35748Ca9F64d5",
  "type": [
    [ “VerifiableCredential”,“VerifiableIdCredential”]
  ]
}

The user will receive a presentation request in VIDwallet. By accepting this request, the user actively gives consent to share the data and VIDwallet will generate a presentation.

Retrieve the Presentation

The VIDcredentials component securely stores the verifiable presentation. VIDcredentials performs a POST to the defined callbackUrl during the onboarding process including the following payload:

{
  "message": "Your requested presentation is ready to be downloaded.",
  "url": “https://api.vidchain.net/api/v1/attributes/0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470”
}

The presentation can be retrieved following the value of the url field.

3. Credential Issuance Flow

The following diagram depicts the process to issue a credential using VIDcredentials:

1. The user starts a credential issuance process.
2. The entity application calls VIDcredentials to issue a verifiable credential that relates to the user's DID.
3. The user’s VIDwallet receives an credential offer.
4. The user accepts the credential offering and stores it in VIDwallet.